package erwiki.api.auth;

import java.security.Principal;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpSession;

import erwiki.api.core.Engine;
import erwiki.api.core.WikiSession;

public interface ISessionMonitor {

	/**
	 * Removes the wiki session associated with the user's HttpRequest from the session cache.
	 *
	 * @param request the user's HTTP request
	 */
	void remove(HttpServletRequest request);

	/**
	 * Removes the wiki session associated with the user's HTTP request from the cache of wiki sessions,
	 * typically as part of a logout process.
	 *
	 * @param session the user's HTTP session
	 */
	void remove(String session);

	/**
	 * Returns the current number of active wiki sessions.
	 * 
	 * @return the number of sessions
	 */
	int sessions();

	/**
	 * <p>
	 * Returns the current wiki users as a sorted array of Principal objects. The principals are those
	 * returned by each WikiSession's {@link WikiSession#getUserPrincipal()}'s method.
	 * </p>
	 * <p>
	 * To obtain the list of current WikiSessions, we iterate through our session Map and obtain the
	 * list of values, which are WikiSessions wrapped in {@link java.lang.ref.WeakReference} objects.
	 * Those <code>WeakReference</code>s whose <code>get()</code> method returns non-<code>null</code>
	 * values are valid sessions.
	 * </p>
	 *
	 * @return the array of user principals
	 */
	Principal[] userPrincipals();

	/**
	 * Метод ориентируется на UISession, которую получает вызовом RWT.getUISession().</br>
	 * Так же, использует HttpServletRequest, из RWT.getRequest().
	 * <p>
	 * Это фабричный метод, который возвращает объект WikiSession, связанный с текущей UI сессией RAP.
	 * Этот метод ищет связанный HttpSession с идентификатором, во внутреннем WeakHashMap и пытается
	 * получить WikiSession. Если сессия wiki не будет найдена, то она создается. Этот метод
	 * гарантированно всегда возвращает WikiSession, связанную с сеансом пользователя, хотя статус
	 * аутентификации непредсказуем до тех пор, пока пользователь не попытается войти в систему.
	 * <p>
	 * :FVK: - переписать:</br>
	 * Если параметр httpSession имеет значение <code>null</code>, то возвращается синтетический
	 * {@link #guestSession(Engine)}.
	 * <p>
	 * Внутри сеанс хранится в HashMap; ключи - это идентификаторы HttpSession, а значения -
	 * {@link java.lang.ref.WeakReference}-обертки WikiSessions.
	 * <p>
	 * :FVK: - верно ли следующее?</br>
	 * При создании WikiSession этот метод присоединяет прослушиватель событий WikiEventListener к
	 * GroupManager, AccountManager и AuthenticationManager, так что изменения в пользователях, группах,
	 * логинах и т. д. обнаруживаются автоматически.
	 * 
	 * @return
	 */
	WikiSession getWikiSession();

	/**
	 * Поиск WikiSession, связанной с Http-сеансом пользователя.</br>
	 * Если не найдена связанная сессиия, то возвращается экземпляр синтетической guestSession(Engine).
	 * <p>
	 * <b>NOTE:</b> работает без контекста RAP.
	 *
	 * @param request
	 * @return
	 */
	WikiSession getWikiSession(HttpServletRequest request);

	WikiSession createHeadlessSession();

	/**
	 * Factory method that creates a new "guest" session containing a single user Principal
	 * {@link org.apache.wiki.auth.WikiPrincipal#GUEST}, plus the role principals {@link Role#ALL} and
	 * {@link Role#ANONYMOUS}. This method also adds the session as a listener for GroupManager,
	 * AuthenticationManager and AccountManager events.
	 *
	 * @return the guest wiki session
	 */
	WikiSession createGuestSession(String sid);

	/**
	 * Returns ID os specified wiki session.
	 * 
	 * @param session wiki session.
	 * @return ID of specified wiki session.
	 */
	String getSessionId(WikiSession session);


}
